/*
 *
 *      Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 *  this list of conditions and the following disclaimer.
 *  Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *  Neither the name of the pig4cloud.com developer nor the names of its
 *  contributors may be used to endorse or promote products derived from
 *  this software without specific prior written permission.
 *  Author: lengleng (wangiegie@gmail.com)
 *
 */

package com.pig4cloud.pig.admin.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.pig4cloud.pig.admin.api.entity.SysRole;
import com.pig4cloud.pig.admin.api.vo.RoleExcelVO;
import com.pig4cloud.pig.admin.api.vo.RoleVO;
import com.pig4cloud.pig.common.core.util.R;
import org.springframework.validation.BindingResult;

import java.util.List;

/**
 * 系统角色服务接口
 * <p>
 * 提供角色管理的核心业务逻辑处理，包括角色的增删改查、权限分配、菜单绑定等功能。
 * 支持角色的批量导入导出，是基于RBAC权限模型的核心组件
 * </p>
 *
 * @author lengleng
 * @since 2017-10-29
 */
public interface SysRoleService extends IService<SysRole> {

	/**
	 * 通过用户ID查询角色信息
	 * <p>
	 * 查询指定用户所拥有的所有角色，用于权限验证和用户信息展示。
	 * 不包含已禁用的角色
	 * </p>
	 * 
	 * @param userId 用户ID
	 * @return 用户所属的角色信息列表
	 */
	List<SysRole> listRolesByUserId(Long userId);

	/**
	 * 根据角色ID列表查询角色信息
	 * <p>
	 * 批量查询多个角色的详细信息，支持缓存优化。
	 * 常用于权限校验和角色信息回显
	 * </p>
	 * 
	 * @param roleIdList 角色ID列表，不能为空
	 * @param key 缓存键值，用于缓存优化
	 * @return 查询到的角色列表
	 */
	List<SysRole> listRolesByRoleIds(List<Long> roleIdList, String key);

	/**
	 * 批量删除角色
	 * <p>
	 * 删除指定的角色，同时清理相关的用户角色关联、角色菜单关联。
	 * 如果角色下存在用户，则不允许删除
	 * </p>
	 * 
	 * @param ids 要删除的角色ID数组
	 * @return 删除是否成功
	 */
	Boolean removeRoleByIds(Long[] ids);

	/**
	 * 更新角色菜单权限
	 * <p>
	 * 重新分配角色的菜单权限，会先清除旧的权限关联，再建立新的关联。
	 * 支持完整的菜单树结构，包括目录、菜单、按钮权限
	 * </p>
	 * 
	 * @param roleVo 包含角色ID和菜单ID列表的VO对象
	 * @return 更新是否成功
	 */
	Boolean updateRoleMenus(RoleVO roleVo);

	/**
	 * Excel批量导入角色
	 * <p>
	 * 支持通过Excel批量创建角色，自动处理数据验证和重复检查。
	 * 导入失败时会返回详细的错误信息
	 * </p>
	 * 
	 * @param excelVOList Excel解析后的角色数据列表
	 * @param bindingResult 数据验证结果，包含格式错误等信息
	 * @return 导入结果，包含成功数量和失败详情
	 */
	R importRole(List<RoleExcelVO> excelVOList, BindingResult bindingResult);

	/**
	 * 查询全部角色列表
	 * <p>
	 * 不分页查询所有角色，主要用于Excel导出功能。
	 * 返回数据已转换为Excel导出格式
	 * </p>
	 * 
	 * @return 角色Excel视图对象列表
	 */
	List<RoleExcelVO> listRoles();

}
